home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok59.lha / AmokEd_V1.02b / doc / ARexxMac.doc < prev    next >
Text File  |  1993-08-15  |  10KB  |  227 lines
  1.  
  2. The following text has been writen by Kim DeVaughn, who implemented
  3. the ARexx-Interface in DME. It has not been modified for AmokEd!
  4. But in some weeks I'll write an extra dokument for AmokEd.
  5.  
  6. +++hartmut
  7.  
  8. .....8<-------------------
  9.  
  10. This is the first general release (vX.29c), of Matt Dillon's DME editor
  11. with an interface to Bill Hawes' ARexx REXX language interpreter, and is
  12. functionally identical to Matt's v1.29c release (excepting the ARexx
  13. interface, of course).
  14.  
  15. ARexx/REXX provides a powerful macro control language capability that can be
  16. added to just about any application ... pretty easily, as it turns out.
  17.  
  18. I chose to add it's macro facilities to my favorite editor for a couple of
  19. reasons.  First, as an exercise, to find out just how to interface ARexx to
  20. an application, and second to make true named macros available to DME.
  21.  
  22. I think I've managed to do both, and would now like for other people to have
  23. a bash at it, and see what I've overlooked.
  24.  
  25. With that in mind, here are a few, uh, implementation notes.  I solicit your
  26. feedback.  Thanks!
  27.  
  28.  
  29.      0 - The following included ARexx macros actually do something useful
  30.          (though relatively simple).  They work, and are setup to process
  31.          any ARexx generated or DME generated error conditions (such as
  32.          not having enough room to save a file to).  At this time, some
  33.          of the error messages that DME puts in the titlebar, may get
  34.          overwritten by an "OK" message.  This is due to the limited number
  35.          of changes that were made to the DME code, and should improve in
  36.          subsequent releases.  See further remarks on error handling below.
  37.  
  38.          The useful macros are: save.dme, put.dme, putd.dme, get.dme, and
  39.          bot.dme.  They are implementations of the VM/CMS XEDIT functions
  40.          of the similar names.
  41.  
  42.          Any other included macros (.dme files) are mostly nonsense as far
  43.          as functionallity.  They were used in helping be to help debug the
  44.          interface, and are included only to illustrate some of the things
  45.          one might do (like nested macro calls, etc).  So be kind about
  46.          them :-)!
  47.  
  48.  
  49.      1 - ARexx macros for DME must be named the same as the command string
  50.          that will be be used to invoke them.
  51.  
  52.  
  53.      2 - ARexx macros for DME should be given the filename extension ".dme".
  54.  
  55.  
  56.      3 - ARexx macros for DME must reside in the current directory, or the
  57.          directory "rexx:" is assigned to.  The current directory is searched
  58.          first, followed by the "rexx:" directory.
  59.  
  60.  
  61.      4 - ARexx macros for DME may be invoked in three ways:
  62.  
  63.          a - Explicitly, using one of the DME "rx" commands (e.g., "rx macname",
  64.              "rx1 macname arg", or "rx2 macname arg1 arg2").
  65.  
  66.              The "rx" command is used to call an ARexx command without passing
  67.              it any arguments; the "rx1" and "rx2" commands are used to pass
  68.              the ARexx macro one or two arguments respectively.  If more args
  69.              need to be passed to the ARexx macro, rx1 (or rx2) may be used by
  70.              quoting them  E.g., to pass a macro 5 args, you might use the
  71.              command: "rx2 macname (arg1 arg2) `arg3 arg4 arg5'", or possibly:
  72.              "rx1 macname (arg1 arg2 arg3 arg4 arg5)".  The "args.dme" macro
  73.              is included for you to experiment with.
  74.  
  75.              These forms may be embedded in a DME command string (e.g.,
  76.              "bottom rx macname find foo" works), unlike the implicit form of
  77.              invocation below.
  78.  
  79.  
  80.          b - Implicitly, by specifying the name of a macro on DME's command
  81.              line, followed by any arguments to be passed to the macro.
  82.  
  83.              The macro name must be the first (or only) token in the command
  84.              string (e.g., "macname huey dewey louie"), and must NOT be the
  85.              same as an internal DME command.
  86.  
  87.              Note that the entire command string is passed to the ARexx
  88.              interperter "as is", with the case of any arguments, special
  89.              characters, etc. being preserved.
  90.  
  91.  
  92.          c - By keystroke.  The implicit form of a macro command line, with
  93.              any arguments, may be mapped to a key just as a DME command is.
  94.              Currently however, partial bindings are not supported.  That is,
  95.              "escimm" cannot be used to bind the macro name to a key, leaving
  96.              the argument(s), if any, to added in the command line.  This
  97.              will be fixed in a future release.
  98.  
  99.              The explicit forms ("rx macname", etc.) may be bound in any
  100.              command sequence.
  101.  
  102.  
  103.      5 - Macro files may contain DME commands, or other macro names.  There
  104.          is currently no "depth checking", nor checking for circular calls
  105.          (A calls B, with B calling A).  If you create such things, you will
  106.          probably get what you deserve :-)!
  107.  
  108.          Also, I think there is a problem in getting arguments for a second
  109.          macro that are specified in the first macro passed back thru DME and
  110.          on to the second macro.  I'm investigating this.
  111.  
  112.          Note that ARexx capitalizes arguments that are to be passed to DME
  113.          if they are not quoted.  So if you want to give the command: find Foo,
  114.          specify it as: find "Foo".  Otherwise you'll be looking for: FOO.
  115.  
  116.  
  117.      6 - Hitting Ctrl-C will result in an "invalid message packet" error
  118.          message from ARexx (code = 10).  This doesn't seem to cause any
  119.          problems, but to avoid it, remap c-c to the new "null" command
  120.          (which does absolutely nothing functional [i.e., map c-c `null'],
  121.          or some other DME command.
  122.  
  123.  
  124.      7 - I have not tested to see if explicit ARexx macro calls work inside
  125.          of complex DME macros, nor with the $scanf facility.
  126.  
  127.  
  128.      8 - Error handling is not all it should be.  Second level (or lower)
  129.          macro error messages (in the title bar), may be overwritten by
  130.          a higher level "OK" (or other message).
  131.  
  132.          Not all DME commands return completion codes, and the "sense" of
  133.          them is opposite that of ARexx (in DME, failure = 0, success = 1).
  134.          This makes figuring out who did what, what worked and what didn't,
  135.          and what went wrong, a little difficult.  I'm sure I don't have it
  136.          all "right" (and probably *can't* without alot of work to DME,
  137.          which I explicitely don't want to do ... yet, anyway).
  138.  
  139.          I have the general definition of an error handling strategy roughed
  140.          out (see the rexx.h file), but am still considering alternatives.
  141.          This is likely to change, so don't count on the proposed method
  142.          just yet.
  143.  
  144.          The binding to the ARexx ErrorMsg() function isn't working with
  145.          Manx yet (because I need to change the "rexxglue" binding, I think).
  146.          So right now I don't display the actual ARexx error messages, and
  147.          have to give you just the code.
  148.  
  149.          This whole area needs lots of work ...
  150.  
  151.  
  152.      9 - Yes, I know the title bar blinking while a macro is running can be
  153.          distracting.  At least you can sorta see what's happening if *you*
  154.          don't blink :-).
  155.  
  156.  
  157.     10 - Compiled using Manx v3.60a (v3.40a/b works too).
  158.  
  159.  
  160.     11 - To compile, set AREXX to 1 in defs.h, and "make rexx".  Set AREXX
  161.          to 0, and use "make norexx"  to create a non-ARexx, vanilla version.
  162.  
  163.          The Makefiles assume you have a precompiled header file in vd0:include
  164.          called "symbols.m" (all of the Amiga .h's).  Also you need to have
  165.          the rexx includes in the "include/rexx" directory, and Matt's sup32lib
  166.          includes in "include/sup32".  His "sup32.lib" should be in the current
  167.          directory, or in the directory with teh Manx libs.
  168.  
  169.          For linking, the "rexxbind.o" file is needed.  When make processes
  170.          "rexxbind.asm", you'll need to be sure your assembly language .i
  171.          files are available to the assembler.
  172.  
  173.  
  174.     12 - The ARexx interface adds about 1.5K to the size of the executable
  175.          right now.
  176.  
  177.          This can probably be reduced a little, by removing some of the checking
  178.          done in "rexx.c" following some of the calls to the ARexx functions
  179.          that create/initialize the messages sent to ARexx.  They're just in
  180.          there for CYA at the moment (I think).
  181.  
  182.  
  183.     13 - This implementation uses the COMMAND interface described in the
  184.          ARexx documentation (as opposed to the FUNCTION interface).
  185.  
  186.  
  187.     14 - ARexx is a Copyrighted product by William S. Hawes,  PO Box 308,
  188.          Maynard, MA  01754 (617-568-8695), and is available from him with
  189.          complete documentation for $49.95 U.S. (plus $2 shipping).
  190.  
  191.          It is a very good product, and well worth the money.  *Please* do
  192.          not pirate it!  I've received written permission from Bill allowing
  193.          the redistribution of his include files with DME, or other example
  194.          code, however please note that these files are still Copyrighted
  195.          by Bill, and that if *you* want to distribute them with *your* own
  196.          application, you should obtain your own permission from Bill to
  197.          do so.
  198.  
  199.  
  200.     15 - DME is a Copyrighted, freely redistributable program by Matt
  201.          Dillon, of Berkeley, CA.  It may be distributed for non-profit
  202.          only.  Obviously, I think it's the best editor currently available
  203.          for the Amiga ... otherwise I wouldn't have gone to the trouble to
  204.          add the ARexx interface.
  205.  
  206.          My code falls under the same distribution restrictions as Matt's;
  207.          you may redistribute it freely, but may not use it for profit, nor
  208.          imbed it in a commercial product without prior written permission
  209.          from me.
  210.  
  211.  
  212.     16 - Please report any problems or bugs found in this version to me at
  213.          the address below, and don't bug Matt about them.  He doesn't have
  214.          ARexx (yet), and won't be able to help you out.
  215.  
  216.  
  217. Good luck ... I hope you find the ARexx interface a useful enhancement!
  218.  
  219. /kim   03/31/88
  220.  
  221.  
  222. UUCP:  kim@amdahl.amdahl.com
  223.   or:  {sun,decwrl,hplabs,pyramid,ihnp4,uunet,oliveb,cbosgd,ames}!amdahl!kim
  224. DDD:   408-746-8462
  225. USPS:  Amdahl Corp.  M/S 249,  1250 E. Arques Av,  Sunnyvale, CA 94086
  226.  
  227.